<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD><TITLE>Tcl_Class manual page - TclOO Library Functions</TITLE>
<link rel="stylesheet" href="../docs.css" type="text/css" media="all">
</HEAD>
<BODY><H2><a href="../contents.htm">Tcl8.6.11/Tk8.6.11 Documentation</a> <small>&gt;</small> <a href="contents.htm">Tcl C API</a> <small>&gt;</small> Class</H2>
<H3><A HREF="../UserCmd/contents.htm">Tcl/Tk Applications</A> | <A HREF="../TclCmd/contents.htm">Tcl Commands</A> | <A HREF="../TkCmd/contents.htm">Tk Commands</A> | <A HREF="../ItclCmd/contents.htm">[incr Tcl] Package Commands</A> | <A HREF="../SqliteCmd/contents.htm">SQLite3 Package Commands</A> | <A HREF="../TdbcCmd/contents.htm">TDBC Package Commands</A> | <A HREF="../TdbcmysqlCmd/contents.htm">tdbc::mysql Package Commands</A> | <A HREF="../TdbcodbcCmd/contents.htm">tdbc::odbc Package Commands</A> | <A HREF="../TdbcpostgresCmd/contents.htm">tdbc::postgres Package Commands</A> | <A HREF="../TdbcsqliteCmd/contents.htm">tdbc::sqlite3 Package Commands</A> | <A HREF="../ThreadCmd/contents.htm">Thread Package Commands</A> | <A HREF="../TclLib/contents.htm">Tcl C API</A> | <A HREF="../TkLib/contents.htm">Tk C API</A> | <A HREF="../ItclLib/contents.htm">[incr Tcl] Package C API</A> | <A HREF="../TdbcLib/contents.htm">TDBC Package C API</A></H3>
<DL>
<DD><A HREF="Class.htm#M2" NAME="L86">NAME</A>
<DL><DD>Tcl_ClassGetMetadata, Tcl_ClassSetMetadata, Tcl_CopyObjectInstance, Tcl_GetClassAsObject, Tcl_GetObjectAsClass, Tcl_GetObjectCommand, Tcl_GetObjectFromObj, Tcl_GetObjectName, Tcl_GetObjectNamespace, Tcl_NewObjectInstance, Tcl_ObjectDeleted, Tcl_ObjectGetMetadata, Tcl_ObjectGetMethodNameMapper, Tcl_ObjectSetMetadata, Tcl_ObjectSetMethodNameMapper &mdash; manipulate objects and classes</DD></DL>
<DD><A HREF="Class.htm#M3" NAME="L87">SYNOPSIS</A>
<DL>
<DD><B>#include &lt;tclOO.h&gt;</B>
<DD>Tcl_Object
<DD><B>Tcl_GetObjectFromObj</B>(<I>interp, objPtr</I>)
<DD>Tcl_Object
<DD><B>Tcl_GetClassAsObject</B>(<I>class</I>)
<DD>Tcl_Class
<DD><B>Tcl_GetObjectAsClass</B>(<I>object</I>)
<DD>Tcl_Obj *
<DD><B>Tcl_GetObjectName</B>(<I>interp, object</I>)
<DD>Tcl_Command
<DD><B>Tcl_GetObjectCommand</B>(<I>object</I>)
<DD>Tcl_Namespace *
<DD><B>Tcl_GetObjectNamespace</B>(<I>object</I>)
<DD>Tcl_Object
<DD><B>Tcl_NewObjectInstance</B>(<I>interp, class, name, nsName, objc, objv, skip</I>)
<DD>Tcl_Object
<DD><B>Tcl_CopyObjectInstance</B>(<I>interp, object, name, nsName</I>)
<DD>int
<DD><B>Tcl_ObjectDeleted</B>(<I>object</I>)
<DD>ClientData
<DD><B>Tcl_ObjectGetMetadata</B>(<I>object, metaTypePtr</I>)
<DD><B>Tcl_ObjectSetMetadata</B>(<I>object, metaTypePtr, metadata</I>)
<DD>ClientData
<DD><B>Tcl_ClassGetMetadata</B>(<I>class, metaTypePtr</I>)
<DD><B>Tcl_ClassSetMetadata</B>(<I>class, metaTypePtr, metadata</I>)
<DD>Tcl_ObjectMapMethodNameProc
<DD><B>Tcl_ObjectGetMethodNameMapper</B>(<I>object</I>)
<DD><B>Tcl_ObjectSetMethodNameMapper</B>(<I>object</I>, <I>methodNameMapper</I>)
</DL>
<DD><A HREF="Class.htm#M4" NAME="L88">ARGUMENTS</A>
<DL class="arguments">
</DL>
<DD><A HREF="Class.htm#M5" NAME="L89">DESCRIPTION</A>
<DD><A HREF="Class.htm#M6" NAME="L90">OBJECT AND CLASS METADATA</A>
<DD><A HREF="Class.htm#M7" NAME="L91">TCL_OBJECTMETADATATYPE STRUCTURE</A>
<DD><A HREF="Class.htm#M8" NAME="L92">TCL_OBJECTMETADATADELETEPROC FUNCTION SIGNATURE</A>
<DD><A HREF="Class.htm#M9" NAME="L93">TCL_CLONEPROC FUNCTION SIGNATURE</A>
<DD><A HREF="Class.htm#M10" NAME="L94">OBJECT METHOD NAME MAPPING</A>
<DD><A HREF="Class.htm#M11" NAME="L95">TCL_OBJECTMAPMETHODNAMEPROC FUNCTION SIGNATURE</A>
<DD><A HREF="Class.htm#M12" NAME="L96">SEE ALSO</A>
<DD><A HREF="Class.htm#M13" NAME="L97">KEYWORDS</A>
</DL>
<H3><A NAME="M2">NAME</A></H3>
Tcl_ClassGetMetadata, Tcl_ClassSetMetadata, Tcl_CopyObjectInstance, Tcl_GetClassAsObject, Tcl_GetObjectAsClass, Tcl_GetObjectCommand, Tcl_GetObjectFromObj, Tcl_GetObjectName, Tcl_GetObjectNamespace, Tcl_NewObjectInstance, Tcl_ObjectDeleted, Tcl_ObjectGetMetadata, Tcl_ObjectGetMethodNameMapper, Tcl_ObjectSetMetadata, Tcl_ObjectSetMethodNameMapper &mdash; manipulate objects and classes
<H3><A NAME="M3">SYNOPSIS</A></H3>
<B>#include &lt;tclOO.h&gt;</B><BR>
Tcl_Object<BR>
<B>Tcl_GetObjectFromObj</B>(<I>interp, objPtr</I>)<BR>
Tcl_Object<BR>
<B>Tcl_GetClassAsObject</B>(<I>class</I>)<BR>
Tcl_Class<BR>
<B>Tcl_GetObjectAsClass</B>(<I>object</I>)<BR>
<A HREF="../TclLib/Object.htm">Tcl_Obj</A> *<BR>
<B>Tcl_GetObjectName</B>(<I>interp, object</I>)<BR>
<A HREF="../TclLib/CrtObjCmd.htm">Tcl_Command</A><BR>
<B>Tcl_GetObjectCommand</B>(<I>object</I>)<BR>
<A HREF="../TclLib/Namespace.htm">Tcl_Namespace</A> *<BR>
<B>Tcl_GetObjectNamespace</B>(<I>object</I>)<BR>
Tcl_Object<BR>
<B>Tcl_NewObjectInstance</B>(<I>interp, class, name, nsName, objc, objv, skip</I>)<BR>
Tcl_Object<BR>
<B>Tcl_CopyObjectInstance</B>(<I>interp, object, name, nsName</I>)<BR>
int<BR>
<B>Tcl_ObjectDeleted</B>(<I>object</I>)<BR>
ClientData<BR>
<B>Tcl_ObjectGetMetadata</B>(<I>object, metaTypePtr</I>)<BR>
<B>Tcl_ObjectSetMetadata</B>(<I>object, metaTypePtr, metadata</I>)<BR>
ClientData<BR>
<B>Tcl_ClassGetMetadata</B>(<I>class, metaTypePtr</I>)<BR>
<B>Tcl_ClassSetMetadata</B>(<I>class, metaTypePtr, metadata</I>)<BR>
Tcl_ObjectMapMethodNameProc<BR>
<B>Tcl_ObjectGetMethodNameMapper</B>(<I>object</I>)<BR>
<B>Tcl_ObjectSetMethodNameMapper</B>(<I>object</I>, <I>methodNameMapper</I>)<BR>
<H3><A NAME="M4">ARGUMENTS</A></H3>
<DL class="arguments">
<DT><A HREF="../TclLib/Interp.htm">Tcl_Interp</A> <B>*interp</B> (in/out)<DD>
Interpreter providing the context for looking up or creating an object, and
into whose result error messages will be written on failure.
<P><DT><A HREF="../TclLib/Object.htm">Tcl_Obj</A> <B>*objPtr</B> (in)<DD>
The name of the object to look up.
<P><DT>Tcl_Object <B>object</B> (in)<DD>
Reference to the object to operate upon.
<P><DT>Tcl_Class <B>class</B> (in)<DD>
Reference to the class to operate upon.
<P><DT>const char <B>*name</B> (in)<DD>
The name of the object to create, or NULL if a new unused name is to be
automatically selected.
<P><DT>const char <B>*nsName</B> (in)<DD>
The name of the namespace to create for the object's private use, or NULL if a
new unused name is to be automatically selected. The namespace must not
already exist.
<P><DT>int <B>objc</B> (in)<DD>
The number of elements in the <I>objv</I> array.
<P><DT><A HREF="../TclLib/Object.htm">Tcl_Obj</A> *const <B>*objv</B> (in)<DD>
The arguments to the command to create the instance of the class.
<P><DT>int <B>skip</B> (in)<DD>
The number of arguments at the start of the argument array, <I>objv</I>, that
are not arguments to any constructors. This allows the generation of correct
error messages even when complicated calling patterns are used (e.g., via the
<B><A HREF="../TclCmd/next.htm">next</A></B> command).
<P><DT>Tcl_ObjectMetadataType <B>*metaTypePtr</B> (in)<DD>
The type of <I>metadata</I> being set with <B>Tcl_ClassSetMetadata</B> or
retrieved with <B>Tcl_ClassGetMetadata</B>.
<P><DT>ClientData <B>metadata</B> (in)<DD>
An item of metadata to attach to the class, or NULL to remove the metadata
associated with a particular <I>metaTypePtr</I>.
<P><DT>Tcl_ObjectMapMethodNameProc <B>methodNameMapper</B> (in)<DD>
A pointer to a function to call to adjust the mapping of objects and method
names to implementations, or NULL when no such mapping is required.
<P></DL>
<H3><A NAME="M5">DESCRIPTION</A></H3>
Objects are typed entities that have a set of operations (&quot;methods&quot;)
associated with them. Classes are objects that can manufacture objects. Each
class can be viewed as an object itself; the object view can be retrieved
using <B>Tcl_GetClassAsObject</B> which always returns the object when applied
to a non-destroyed class, and an object can be viewed as a class with the aid
of the <B>Tcl_GetObjectAsClass</B> (which either returns the class, or NULL if
the object is not a class). An object may be looked up using the
<B>Tcl_GetObjectFromObj</B> function, which either returns an object or NULL
(with an error message in the interpreter result) if the object cannot be
found. The correct way to look up a class by name is to look up the object
with that name, and then to use <B>Tcl_GetObjectAsClass</B>.
<P>
Every object has its own command and namespace associated with it. The command
may be retrieved using the <B>Tcl_GetObjectCommand</B> function, the name of
the object (and hence the name of the command) with <B>Tcl_GetObjectName</B>,
and the namespace may be retrieved using the <B>Tcl_GetObjectNamespace</B>
function. Note that the <A HREF="../TclLib/Object.htm">Tcl_Obj</A> reference returned by <B>Tcl_GetObjectName</B>
is a shared reference. You can also get whether the object has been marked for
deletion with <B>Tcl_ObjectDeleted</B> (it returns true if deletion of the
object has begun); this can be useful during the processing of methods.
<P>
Instances of classes are created using <B>Tcl_NewObjectInstance</B>, which
creates an object from any class (and which is internally called by both
the <B>create</B> and <B>new</B> methods of the <B><A HREF="../TclCmd/class.htm">oo::class</A></B> class). It takes
parameters that optionally give the name of the object and namespace to
create, and which describe the arguments to pass to the class's constructor
(if any). The result of the function will be either a reference to the newly
created object, or NULL if the creation failed (when an error message will be
left in the interpreter result). In addition, objects may be copied by using
<B>Tcl_CopyObjectInstance</B> which creates a copy of an object without running
any constructors.
<P>
Note that the lifetime management of objects is handled internally within
TclOO, and does not use <B><A HREF="../TclLib/Preserve.htm">Tcl_Preserve</A></B>. <I>It is not safe to put a
Tcl_Object handle in a C structure with a lifespan different to the object;</I>
you should use the object's command name (as retrieved with
<B>Tcl_GetObjectName</B>) instead. It is safe to use a Tcl_Object handle for
the lifespan of a call of a method on that object; handles do not become
invalid while there is an outstanding call on their object (even if the only
operation guaranteed to be safe on them is <B>Tcl_ObjectDeleted</B>; the other
operations are only guaranteed to work on non-deleted objects).
<H3><A NAME="M6">OBJECT AND CLASS METADATA</A></H3>
Every object and every class may have arbitrary amounts of metadata attached
to it, which the object or class attaches no meaning to beyond what is
described in a Tcl_ObjectMetadataType structure instance. Metadata to be
attached is described by the type of the metadata (given in the
<I>metaTypePtr</I> argument) and an arbitrary pointer (the <I>metadata</I>
argument) that are given to <B>Tcl_ObjectSetMetadata</B> and
<B>Tcl_ClassSetMetadata</B>, and a particular piece of metadata can be
retrieved given its type using <B>Tcl_ObjectGetMetadata</B> and
<B>Tcl_ClassGetMetadata</B>. If the <I>metadata</I> parameter to either
<B>Tcl_ObjectSetMetadata</B> or <B>Tcl_ClassSetMetadata</B> is NULL, the
metadata is removed if it was attached, and the results of
<B>Tcl_ObjectGetMetadata</B> and <B>Tcl_ClassGetMetadata</B> are NULL if the
given type of metadata was not attached. It is not an error to request or
remove a piece of metadata that was not attached.
<H4><A NAME="M7">TCL_OBJECTMETADATATYPE STRUCTURE</A></H4>
The contents of the Tcl_ObjectMetadataType structure are as follows:
<P>
<PRE>typedef const struct {
    int <I>version</I>;
    const char *<I>name</I>;
    Tcl_ObjectMetadataDeleteProc *<I>deleteProc</I>;
    Tcl_CloneProc *<I>cloneProc</I>;
} <B>Tcl_ObjectMetadataType</B>;</PRE>
<P>
The <I>version</I> field allows for future expansion of the structure, and
should always be declared equal to TCL_OO_METADATA_VERSION_CURRENT. The
<I>name</I> field provides a human-readable name for the type, and is reserved
for debugging.
<P>
The <I>deleteProc</I> field gives a function of type
Tcl_ObjectMetadataDeleteProc that is used to delete a particular piece of
metadata, and is called when the attached metadata is replaced or removed; the
field must not be NULL.
<P>
The <I>cloneProc</I> field gives a function that is used to copy a piece of
metadata (used when a copy of an object is created using
<B>Tcl_CopyObjectInstance</B>); if NULL, the metadata will be just directly
copied.
<H4><A NAME="M8">TCL_OBJECTMETADATADELETEPROC FUNCTION SIGNATURE</A></H4>
Functions matching this signature are used to delete metadata associated with
a class or object.
<P>
<PRE>typedef void <B>Tcl_ObjectMetadataDeleteProc</B>(
        ClientData <I>metadata</I>);</PRE>
<P>
The <I>metadata</I> argument gives the address of the metadata to be
deleted.
<H4><A NAME="M9">TCL_CLONEPROC FUNCTION SIGNATURE</A></H4>
Functions matching this signature are used to create copies of metadata
associated with a class or object.
<P>
<PRE>typedef int <B>Tcl_CloneProc</B>(
        <A HREF="../TclLib/Interp.htm">Tcl_Interp</A> *<I>interp</I>,
        ClientData <I>srcMetadata</I>,
        ClientData *<I>dstMetadataPtr</I>);</PRE>
<P>
The <I>interp</I> argument gives a place to write an error message when the
attempt to clone the object is to fail, in which case the clone procedure must
also return TCL_ERROR; it should return TCL_OK otherwise.
The <I>srcMetadata</I> argument gives the address of the metadata to be cloned,
and the cloned metadata should be written into the variable pointed to by
<I>dstMetadataPtr</I>; a NULL should be written if the metadata is to not be
cloned but the overall object copy operation is still to succeed.
<H3><A NAME="M10">OBJECT METHOD NAME MAPPING</A></H3>
It is possible to control, on a per-object basis, what methods are invoked
when a particular method is invoked. Normally this is done by looking up the
method name in the object and then in the class hierarchy, but fine control of
exactly what the value used to perform the look up is afforded through the
ability to set a method name mapper callback via
<B>Tcl_ObjectSetMethodNameMapper</B> (and its introspection counterpart,
<B>Tcl_ObjectGetMethodNameMapper</B>, which returns the current mapper). The
current mapper (if any) is invoked immediately before looking up what chain of
method implementations is to be used.
<H4><A NAME="M11">TCL_OBJECTMAPMETHODNAMEPROC FUNCTION SIGNATURE</A></H4>
The <I>Tcl_ObjectMapMethodNameProc</I> callback is defined as follows:
<P>
<PRE>typedef int <B>Tcl_ObjectMapMethodNameProc</B>(
        <A HREF="../TclLib/Interp.htm">Tcl_Interp</A> *<I>interp</I>,
        Tcl_Object <I>object</I>,
        Tcl_Class *<I>startClsPtr</I>,
        <A HREF="../TclLib/Object.htm">Tcl_Obj</A> *<I>methodNameObj</I>);</PRE>
<P>
If the result is TCL_OK, the remapping is assumed to have been done. If the
result is TCL_ERROR, an error message will have been left in <I>interp</I> and
the method call will fail. If the result is TCL_BREAK, the standard method
name lookup rules will be used; the behavior of other result codes is
currently undefined. The <I>object</I> parameter says which object is being
processed. The <I>startClsPtr</I> parameter points to a variable that contains
the first class to provide a definition in the method chain to process, or
NULL if the whole chain is to be processed (the argument itself is never
NULL); this variable may be updated by the callback. The <I>methodNameObj</I>
parameter gives an unshared object containing the name of the method being
invoked, as provided by the user; this object may be updated by the callback.
<H3><A NAME="M12">SEE ALSO</A></H3>
<B>Method</B>, <B><A HREF="../TclCmd/class.htm">oo::class</A></B>, <B><A HREF="../TclCmd/copy.htm">oo::copy</A></B>, <B><A HREF="../TclCmd/define.htm">oo::define</A></B>, <B><A HREF="../TclCmd/object.htm">oo::object</A></B>
<H3><A NAME="M13">KEYWORDS</A></H3>
<A href="../Keywords/C.htm#class">class</A>, <A href="../Keywords/C.htm#constructor">constructor</A>, <A href="../Keywords/O.htm#object">object</A>
<div class="copy">Copyright &copy; 2007 Donal K. Fellows
</div>
</BODY></HTML>
